<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
<!-- creator-debugger.qdoc -->
  <title>Using Debugging Helpers | Qt Creator Manual</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="index.html">Qt Creator Manual</a></td><td >Using Debugging Helpers</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="index.html">Qt Creator Manual 4.11.1</a></td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
  <link rel="prev" href="creator-debug-mode.html" />
  <link rel="next" href="creator-debugging-qml.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="creator-debug-mode.html">Interacting with the Debugger</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-debugging-qml.html">Debugging Qt Quick Projects</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#extending-debugging-helpers">Extending Debugging Helpers</a></li>
<li class="level2"><a href="#adding-custom-debugging-helpers">Adding Custom Debugging Helpers</a></li>
<li class="level2"><a href="#debugging-helper-overview">Debugging Helper Overview</a></li>
<li class="level2"><a href="#debugging-helper-implementation">Debugging Helper Implementation</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Using Debugging Helpers</h1>
<span class="subtitle"></span>
<!-- $$$creator-debugging-helpers.html-description -->
<div class="descr"> <a name="details"></a>
<p>Structured data, such as objects of <code>class</code>, <code>struct</code>, or <code>union</code> types, is displayed in the <b>Locals</b> and <b>Expressions</b> views as part of a tree. To access sub-structures of the objects, expand the tree nodes. The sub-structures are presented in their in-memory order, unless the <b>Sort Members of Classes and Structs Alphabetically</b> option from the context menu is selected.</p>
<p>Similarly, pointers are displayed as a tree item with a single child item representing the target of the pointer. In case the context menu item <b>Dereference Pointers Automatically</b> is selected, the pointer and the target are combined into a single entry, showing the name and the type of the pointer and the value of the target.</p>
<p>This standard representation is good enough for the examination of simple structures, but it does usually not give enough insight into more complex structures, such as <code>QObjects</code> or associative containers. These items are internally represented by a complex arrangement of pointers, often highly optimized, with part of the data not directly accessible through neither sub-structures nor pointers.</p>
<p>To give the user simple access also to these items, Qt Creator employs Python scripts that are called <i>debugging helpers</i>. Debugging helpers are always automatically used. To force a plain C-like display of structures, select <b>Tools</b> &gt; <b>Options</b> &gt; <b>Debugger</b> &gt; <b>Locals &amp; Expressions</b>, and then deselect the <b>Use Debugging Helper</b> check box. This will still use the Python scripts, but generate more basic output. To force the plain display for a single object or for all objects of a given type, select the corresponding option from the context menu.</p>
<p>Qt Creator ships with debugging helpers for more than 200 of the most popular Qt classes, standard C++ containers, and smart pointers, covering the usual needs of a C++ application developer out-of-the-box.</p>
<a name="extending-debugging-helpers"></a>
<h2 id="extending-debugging-helpers">Extending Debugging Helpers</h2>
<p>Qt Creator uses Python scripts to translate raw memory contents and type information data from native debugger backends (GDB, LLDB, and CDB are currently supported) into the form presented to the user in the <b>Locals</b> and <b>Expressions</b> views.</p>
<p>Unlike GDB's <a href="https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html#Pretty-Printing">pretty printers</a> and LLDB's <a href="http://lldb.llvm.org/varformats.html">data formatters</a>, Qt Creator's debugging helpers are independent of the native debugging backend. That is, the same code can be used with GDB on Linux, LLDB on <a href="nolink">macOS</a>, and CDB on Windows, or any other platform on which at least one of the three supported backends is available.</p>
<a name="adding-custom-debugging-helpers"></a>
<h3 id="adding-custom-debugging-helpers">Adding Custom Debugging Helpers</h3>
<p>To add debugging helpers for your own types, no compilation is required, just adding a few lines of Python. The scripts can address multiple versions of Qt, or of your own library, at the same time.</p>
<p>To add debugging helpers for custom types, add debugging helper implementations to the startup file of the native debuggers (for example, <code>~/.gdbinit</code> or <code>~/.lldbinit</code>) or specify them directly in the <b>Additional Startup Commands</b> in <b>Tools</b> &gt; <b>Options</b> &gt; <b>Debugger</b> &gt; <b>GDB</b>.</p>
<p>To get started with implementing debugging helpers for your own data types, you can put their implementation into the file <code>share/qtcreator/debugger/personaltypes.py</code> in your Qt installation or stand-alone Qt Creator installation. On <a href="nolink">macOS</a>, the file is bundled into the Qt Creator application package, where it is located in the <code>Contents/resources/debugger</code> folder.</p>
<p>The <code>personaltypes.py</code> file contains one example implementation:</p>
<pre class="cpp">

  # def qdump__MapNode(d, value):
  #    d.putValue(&quot;This is the value column contents&quot;)
  #    d.putNumChild(2)
  #    if d.isExpanded():
  #        with Children(d):
  #            # Compact simple case.
  #            d.putSubItem(&quot;key&quot;, value[&quot;key&quot;])
  #            # Same effect, with more customization possibilities.
  #            with SubItem(d, &quot;data&quot;)
  #                d.putItem(&quot;data&quot;, value[&quot;data&quot;])

</pre>
<p>To add debugging helpers:</p>
<ol class="1" type="1"><li>Open the <code>share/qtcreator/debugger/personaltypes.py</code> file for editing. For example, if your Qt installation is located in the <code>Qt5</code> directory on Windows, look in <code>C:\Qt5\Tools\QtCreator\share\qtcreator\debugger</code>. On <a href="nolink">macOS</a>, look in <code>Qt5/Qt Creator.app/Contents/resources/debugger</code>.</li>
<li>Add your dumper implementation to the end of the <code>personaltypes.py</code> file. For more information about implementing debugging helpers, see the following sections.</li>
<li>To prevent <code>personaltypes.py</code> from being overwritten when you update your Qt Creator installation (when updating your Qt installation, for example), copy it to a safe location outside the Qt Creator installation in your file system and specify the location in <b>Tools</b> &gt; <b>Options</b> &gt; <b>Debugger</b> &gt; <b>Locals &amp; Expressions</b> &gt; <b>Extra Debugging Helpers</b>.<p class="centerAlign"><img src="images/qtcreator-debugging-helper-options.png" alt="" /></p></li>
</ol>
<p>The custom debugging helpers will be automatically picked up from <code>personaltypes.py</code> when you start a debugging session in Qt Creator or select <b>Reload Debugging Helpers</b> from the context menu of the <b>Debugger Log</b> view.</p>
<a name="debugging-helper-overview"></a>
<h3 id="debugging-helper-overview">Debugging Helper Overview</h3>
<p>The implementation of a debugging helper typically consists of a single Python function, which needs to be named <code>qdump__NS__Foo</code>, where <code>NS::Foo</code> is the class or class template to be examined. Note that the <code>::</code> scope resolution operator is replaced by double underscores: <code>__</code>. Nested namespaces are possible. Template arguments are not used for the construction of the function name.</p>
<p>Examples:</p>
<ul>
<li>The name for the function implementing a debugging helper for the type <code>namespace Project { template&lt;typename T&gt; struct Foo {..&#x2e; } }</code> is <code>qdump__Project__Foo</code>.</li>
<li>The name for the function implementing a debugging helper for the type <code>std::__1::vector&lt;T&gt;::iterator</code> is <code>qdump__std____1__vector__iterator</code>.</li>
</ul>
<p>Qt Creator's debugger plugin calls this function whenever you want to display an object of this type. The function is passed the following parameters:</p>
<ul>
<li><code>d</code> of type <code>Dumper</code>, an object containing the current settings and providing facilities to build up an object representing a part of the <b>Locals</b> and <b>Expressions</b> views.</li>
<li><code>value</code> of type <code>Value</code>, wrapping either a <a href="https://sourceware.org/gdb/onlinedocs/gdb/Values-From-Inferior.html">gdb.Value</a> or an <a href="http://lldb.llvm.org/cpp_reference/html/classlldb_1_1SBValue.html">lldb.SBValue</a>.</li>
</ul>
<p>The <code>qdump__*</code> function has to feed the Dumper object with certain information that is used to build up the object and its children's display in the <b>Locals</b> and <b>Expressions</b> views.</p>
<p>Example:</p>
<pre class="cpp">

  def qdump__QFiniteStack(d<span class="operator">,</span> value):
      alloc <span class="operator">=</span> value<span class="operator">[</span><span class="string">&quot;_alloc&quot;</span><span class="operator">]</span><span class="operator">.</span>integer()
      size <span class="operator">=</span> value<span class="operator">[</span><span class="string">&quot;_size&quot;</span><span class="operator">]</span><span class="operator">.</span>integer()
      d<span class="operator">.</span>putItemCount(size)
      <span class="keyword">if</span> d<span class="operator">.</span>isExpanded():
          d<span class="operator">.</span>putArrayData(value<span class="operator">[</span><span class="string">&quot;_array&quot;</span><span class="operator">]</span><span class="operator">,</span> size<span class="operator">,</span> value<span class="operator">.</span>type<span class="operator">[</span><span class="number">0</span><span class="operator">]</span>)

</pre>
<p><b>Note: </b>To create dumper functions usable with both LLDB and GDB backends, avoid direct access to the <code>gdb.*</code> and <code>lldb.*</code> namespaces and use the functions of the <code>Dumper</code> class instead.</p><p>To get to the base instance of the object in the debugging helper, use the <code>value.base()</code> function or the following example code:</p>
<pre class="cpp">

  def qdump__A(d<span class="operator">,</span> value):
     t <span class="operator">=</span> value<span class="operator">.</span>members(True)<span class="operator">[</span><span class="number">0</span><span class="operator">]</span><span class="operator">.</span>type
     dptr<span class="operator">,</span> base_v <span class="operator">=</span> value<span class="operator">.</span>split(<span class="char">'p{%s}'</span> <span class="operator">%</span> t<span class="operator">.</span>name)
     d<span class="operator">.</span>putItem(base_v)

</pre>
<p>Debugging helpers can be set up to be called whenever a type name matches a regular expression. To do so, the debugging helper's function name must begin with <code>qdump__</code> (with two underscore characters). In addition, the function needs to have a third parameter called <code>regex</code> with a default value that specifies the regular expression that the type name should match.</p>
<p>For example, the Nim 0.12 compiler assigns artificial names, such as <code>TY1</code> and <code>TY2</code>, to all generic sequences it compiles. To visualize these in Qt Creator, the following debugging helper may be used:</p>
<pre class="cpp">

  def qdump__NimGenericSequence__(d<span class="operator">,</span> value<span class="operator">,</span> regex <span class="operator">=</span> <span class="string">&quot;^TY.*$&quot;</span>):
      size <span class="operator">=</span> value<span class="operator">[</span><span class="string">&quot;Sup&quot;</span><span class="operator">]</span><span class="operator">[</span><span class="string">&quot;len&quot;</span><span class="operator">]</span>
      base <span class="operator">=</span> value<span class="operator">[</span><span class="string">&quot;data&quot;</span><span class="operator">]</span><span class="operator">.</span>dereference()
      typeobj <span class="operator">=</span> base<span class="operator">.</span>dereference()<span class="operator">.</span>type
      d<span class="operator">.</span>putArrayData(base<span class="operator">,</span> size<span class="operator">,</span> typeobj)

</pre>
<a name="debugging-helper-implementation"></a>
<h3 id="debugging-helper-implementation">Debugging Helper Implementation</h3>
<p>A debugging helper creates a description of the displayed data item in a format that is similar to GDB/MI and JSON.</p>
<p>For each line in the <b>Locals</b> and <b>Expressions</b> views, a string like the following needs to be created and channeled to the debugger plugin.</p>
<pre class="cpp">

  { iname<span class="operator">=</span><span class="char">'some internal name'</span><span class="operator">,</span>           <span class="preprocessor"># optional</span>
    address<span class="operator">=</span><span class="char">'object address in memory'</span><span class="operator">,</span>   <span class="preprocessor"># optional</span>
    name<span class="operator">=</span><span class="char">'contents of the name column'</span><span class="operator">,</span>   <span class="preprocessor"># optional</span>
    value<span class="operator">=</span><span class="char">'contents of the value column'</span><span class="operator">,</span>
    type<span class="operator">=</span><span class="char">'contents of the type column'</span><span class="operator">,</span>
    numchild<span class="operator">=</span><span class="char">'number of children'</span><span class="operator">,</span>        <span class="preprocessor"># zero/nonzero is sufficient</span>
    children<span class="operator">=</span><span class="operator">[</span>              <span class="preprocessor"># only needed if item is expanded in view</span>
       {iname<span class="operator">=</span><span class="char">'internal name of first child'</span><span class="operator">,</span>
         }<span class="operator">,</span>
       {iname<span class="operator">=</span><span class="char">'internal name of second child'</span><span class="operator">,</span>
         }<span class="operator">,</span>

    <span class="operator">]</span>}

</pre>
<p>The value of the <code>iname</code> field is the internal name of the object, which consists of a dot-separated list of identifiers, corresponding to the position of the object's representation in the view. If it is not present, it is generated by concatenating the parent object's <code>iname</code>, a dot, and a sequential number.</p>
<p>The value of the <code>name</code> field is displayed in the <b>Name</b> column of the view. If it is not specified, a simple number in brackets is used instead.</p>
<p>As the format is not guaranteed to be stable, it is strongly recommended not to generate the wire format directly, but to use the abstraction layer provided by the Python Dumper classes, specifically the <code>Dumper</code> class itself, and the <code>Dumper:Value</code> and <code>Dumper:Type</code> abstractions.</p>
<p>These provide a complete framework to take care of the <code>iname</code> and <code>addr</code> fields, to handle children of simple types, references, pointers, enums, and known and unknown structs, as well as some convenience functions to handle common situations.</p>
<a name="dumper-class"></a>
<h4 id="dumper-class">Dumper Class</h4>
<p>The <code>Dumper</code> class contains generic bookkeeping, low-level, and convenience functions.</p>
<p>The member functions of the <code>Dumper</code> class are the following:</p>
<ul>
<li><code>putItem(self, value)</code> - The <i>master function</i> that handles basic types, references, pointers, and enums directly, iterates over base classes and class members of compound types, and calls <code>qdump__*</code> functions when appropriate.</li>
<li><code>putIntItem(self, name, value)</code> - Equivalent to:<pre class="cpp">

  with SubItem(self<span class="operator">,</span> name):
      self<span class="operator">.</span>putValue(value)
      self<span class="operator">.</span>putType(<span class="string">&quot;int&quot;</span>)
      self<span class="operator">.</span>putNumChild(<span class="number">0</span>)

</pre>
</li>
<li><code>putBoolItem(self, name, value)</code> - Equivalent to:<pre class="cpp">

  with SubItem(self<span class="operator">,</span> name):
      self<span class="operator">.</span>putValue(value)
      self<span class="operator">.</span>putType(<span class="string">&quot;bool&quot;</span>)
      self<span class="operator">.</span>putNumChild(<span class="number">0</span>)

</pre>
</li>
<li><code>putCallItem(self, name, value, func, *args)</code> - Uses the native debugger backend to place the function call <code>func</code> on the value specified by <i>value</i> and output the resulting item.<p>Native calls are extremely powerful and can leverage existing debugging or logging facilities in the debugged process, for example. However, they should only be used in a controlled environment, and only if there is no other way to access the data, for the following reasons:</p>
<ul>
<li>Direct execution of code is dangerous. It runs native code with the privileges of the debugged process, with the potential to not only corrupt the debugged process, but also to access the disk and network.</li>
<li>Calls cannot be executed when inspecting a core file.</li>
<li>Calls are expensive to set up and execute in the debugger.</li>
</ul>
</li>
<li><code>putArrayData(self, address, itemCount, type)</code> - Creates the number of children specified by <code>itemCount</code> of the type <code>type</code> of an array-like object located at <code>address</code>.</li>
<li><code>putSubItem(self, component, value)</code> - Equivalent to:<pre class="cpp">

  with SubItem(self<span class="operator">,</span> component):
      self<span class="operator">.</span>putItem(value)

</pre>
<p>Exceptions raised by nested function calls are caught and all output produced by <code>putItem</code> is replaced by the output of:</p>
<pre class="cpp">

  except RuntimeError:
      d<span class="operator">.</span>put(<span class="char">'value=&quot;&lt;invalid&gt;&quot;,type=&quot;&lt;unknown&gt;&quot;,numchild=&quot;0&quot;,'</span>)

</pre>
</li>
<li><code>put(self, value)</code> - A low-level function to directly append to the output string. That is also the fastest way to append output.</li>
<li><code>putField(self, name, value)</code> - Appends a <code>name='value'</code> field.</li>
<li><code>childRange(self)</code> - Returns the range of children specified in the current <code>Children</code> scope.</li>
<li><code>putItemCount(self, count)</code> - Appends the field <code>value='&lt;%d items&gt;'</code> to the output.</li>
<li><code>putName(self, name)</code> - Appends the <code>name=''</code> field.</li>
<li><code>putType(self, type, priority=0)</code> - Appends the field <code>type=''</code>, unless the <i>type</i> coincides with the parent's default child type or <code>putType</code> was already called for the current item with a higher value of <code>priority</code>.</li>
<li><code>putBetterType(self, type)</code> - Overrides the last recorded <code>type</code>.</li>
<li><code>putNumChild(self, numchild)</code> - Announces the existence (<code>numchild</code> &gt; 0) or non-existence of child items for the current value. If <code>putNumChild</code> is not explicitly called, the existence of child items is implied.</li>
<li><code>putValue(self, value, encoding = None)</code> - Appends the file <code>value=''</code>, optionally followed by the field <code>valueencoding=''</code>. The <code>value</code> needs to be convertible to a string entirely consisting of alphanumerical values. The <code>encoding</code> parameter can be used to specify the encoding in case the real value had to be encoded in some way to meet the alphanumerical-only requirement. The parameter <code>encoding</code> is either a string of the form <code>codec:itemsize:quote</code> where <code>codec</code> is any of <code>latin1</code>, <code>utf8</code>, <code>utf16</code>, <code>ucs4</code>, <code>int</code>, or <code>float</code>. <code>itemsize</code> gives the size of the basic component of the object if it is not implied by <code>codec</code> and <code>quote</code> specifies whether or not the value should be surrounded by quotes in the display.<p>Example:</p>
<pre class="cpp">

  <span class="preprocessor"># Safe transport of quirky data. Put quotes around the result.</span>
  d<span class="operator">.</span>putValue(d<span class="operator">.</span>hexencode(<span class="string">&quot;ABC\&quot;DEF&quot;</span>)<span class="operator">,</span> <span class="string">&quot;utf8:1:1&quot;</span>)

</pre>
</li>
<li><code>putStringValue(self, value)</code> - Encodes a <a href="http://doc.qt.io/qt-5/qstring.html">QString</a> and calls <code>putValue</code> with the correct <code>encoding</code> setting.</li>
<li><code>putByteArrayValue(self, value)</code> - Encodes a <a href="http://doc.qt.io/qt-5/qbytearray.html">QByteArray</a> and calls <code>putValue</code> with the correct <code>encoding</code> setting.</li>
<li><code>isExpanded(self)</code> - Checks whether the current item is expanded in the view.</li>
<li><code>createType(self, pattern, size = None)</code> - Creates a <code>Dumper.Type</code> object. The exact operation depends on <code>pattern</code>.<ul>
<li>If <code>pattern</code> matches the name of a well-known type, a <code>Dumper.Type</code> object describing this type is returned.</li>
<li>If <code>pattern</code> is the name of a type known to the native backend, the returned type describes the native type.</li>
<li>Otherwise, <code>pattern</code> is used to construct a type description by interpreting a sequence of items describing the field of a structure as follows. Field descriptions consist of one or more characters as follows:<ul>
<li><code>q</code> - Signed 8-byte integral value</li>
<li><code>Q</code> - Unsigned 8-byte integral value</li>
<li><code>i</code> - Signed 4-byte integral value</li>
<li><code>I</code> - Unsigned 4-byte integral value</li>
<li><code>h</code> - Signed 2-byte integral value</li>
<li><code>H</code> - Unsigned 2-byte integral value</li>
<li><code>b</code> - Signed 1-byte integral value</li>
<li><code>B</code> - Unsigned 1-byte integral value</li>
<li><code>d</code> - 8-byte IEEE 754 floating point value</li>
<li><code>f</code> - 4-byte IEEE 754 floating point value</li>
<li><code>p</code> - A pointer, that is, an unsigned integral value of suitable size according to the target architecture</li>
<li><code>@</code> - Suitable padding. The size is determined by the preceding and following field and the target architecture</li>
<li><code>&lt;n&gt;s</code> - A blob of &lt;n&gt; bytes, with implied alignment of 1</li>
<li><code>&lt;typename&gt;</code> - A blob of suitable size and suitable alignment determined by a <code>Dumper.Type</code> with the name <code>typename</code></li>
</ul>
</li>
</ul>
</li>
</ul>
<a name="dumper-type-class"></a>
<h4 id="dumper-type-class">Dumper.Type Class</h4>
<p>The <code>Dumper.Type</code> class describes the type of a piece of data, typically a C++ class or struct, a pointer to a struct, or a primitive type, such as an integral or floating point type.</p>
<p>Type objects, that is, instances of the <code>Dumper.Type</code> class, can be created by native debugger backends, usually by evaluating Debug Information built into or shipped alongside the debugged binary, or created on-the-fly by the debugging helper.</p>
<p>Qt Creator uses the possibility to provide type information on-the-fly for most Qt classes, obliterating the need to use <i>Debug</i> builds of Qt for the purpose of object introspection.</p>
<p>The member functions of the <code>Dumper.Type</code> class are the following:</p>
<ul>
<li><code>name</code> - The name of this type as a string, or <code>None</code> if the type is anonymous.</li>
<li><code>size(self)</code> - Returns the size of an object of this type in bytes.</li>
<li><code>bitsize(self)</code> - Returns the size of an object of this type in bits.</li>
<li><code>(alignment(self)</code> - Returns the required alignment for objects of this type in bytes.</li>
<li><code>deference(self)</code> - Returns the dereferences type for pointer type, <code>None</code> otherwise.</li>
<li><code>pointer(self)</code> - Returns a pointer type that can be dereferenced to this type.</li>
<li><code>target(self)</code> - A convenience function that returns the item type for array types and the dereferenced type for pointers and references.</li>
<li><code>stripTypedefs(self)</code> - Returns the underlying type if this type is an alias.</li>
<li><code>templateArgument(self, position, numeric = False)</code> - Returns the template parameter located at <code>position</code> if this is a templated type. If <code>numeric</code> is <code>True</code>, returns the parameter as an integral value.</li>
<li><code>fields(self)</code> - Returns a list of <code>Dumper:Fields</code> describing the base classes and data members of this type.</li>
</ul>
<a name="dumper-field-class"></a>
<h4 id="dumper-field-class">Dumper.Field Class</h4>
<p>The <code>Dumper.Field</code> class describes a base class or a data member of a type object.</p>
<p>The member function and properties of the <code>Dumper.Field</code> class are the following:</p>
<ul>
<li><code>isBaseClass</code> - Distinguishes between base classes and data members.</li>
<li><code>fieldType(self)</code> - Returns the type of this base class or data member.</li>
<li><code>parentType(self)</code> - Returns the owning type.</li>
<li><code>bitsize(self)</code> - Returns the size of this field in bits.</li>
<li><code>bitpos(self)</code> - Returns the offset of this field in the owning type in bits.</li>
</ul>
<a name="dumper-value-class"></a>
<h4 id="dumper-value-class">Dumper.Value Class</h4>
<p>The <code>Dumper.Value</code> class describes a piece of data, such as instances of C++ classes or primitive data types. It can also be used to describe artificial items that have no direct representation in memory, such as file contents, non-contiguous objects, or collections.</p>
<p>A <code>Dumper.Value</code> has always an associated <code>Dumper.Type</code>. The two main representations of the value's actual data are:</p>
<ul>
<li>Python object following the Python buffer protocol, such as a Python <code>memoryview</code>, or a <code>bytes</code> object. The <code>size()</code> should match the size of this value's type.</li>
<li>An integral value representing a pointer to the begin of the object in the current address space. The size of the object is given by its type's <code>size()</code>.</li>
</ul>
<p>Knowledge of the internal representation of a <code>Dumper.Value</code> is typically not required when creating a debugger helper for it.</p>
<p>The member function and properties of the <code>Dumper.Value</code> class are the following:</p>
<ul>
<li><code>integer(self)</code> - Returns an interpretation of this value as a signed integral value of a suitable size.</li>
<li><code>pointer(self)</code> - Returns an interpretation of this value as a pointer in the current address space.</li>
<li><code>members(self)</code> - Returns a list of <code>Dumper.Value</code> objects representing the base objects and data members of this value.</li>
<li><code>dereference(self)</code> - For values describing pointers, returns the dereferenced value, and <code>None</code> otherwise.</li>
<li><code>cast(self, type)</code> - Returns a value that has the same data as this value, but the type <code>type</code>.</li>
<li><code>address(self)</code> - Returns the address of this value if it consists of a contiguous region in the current address space, and <code>None</code> otherwise.</li>
<li><code>data(self)</code> - Returns the data of this value as a Python <code>bytes</code> object.</li>
<li><code>split(self, pattern)</code> - Returns a list of values created according to <code>pattern</code> from this value's data. Acceptable patterns are the same as for <code>Dumper.createType</code>.</li>
<li><code>dynamicTypeName(self)</code> - Tries to retrieve the name of the dynamic type of this value if this is a base class object. Returns <code>None</code> if that is not possible.</li>
</ul>
<a name="children-and-subitem-class"></a>
<h4 id="children-and-subitem-class">Children and SubItem Class</h4>
<p>The attempt to create child items might lead to errors if data is uninitialized or corrupted. To gracefully recover in such situations, use <code>Children</code> and <code>SubItem</code> <i>Context Managers</i> to create the nested items.</p>
<p>The <code>Children</code> constructor <code>__init__(self, dumper, numChild = 1, childType = None, childNumChild = None, maxNumChild = None, addrBase = None, addrStep = None)</code> uses one mandatory argument and several optional arguments. The mandatory argument refers to the current <code>Dumper</code> object. The optional arguments can be used to specify the number <code>numChild</code> of children, with type <code>childType_</code> and <code>childNumChild_</code> grandchildren each. If <code>maxNumChild</code> is specified, only that many children are displayed. This should be used when dumping container contents that might take overly long otherwise. The parameters <code>addrBase</code> and <code>addrStep</code> can be used to reduce the amount of data produced by the child dumpers. Address printing for the <i>n</i>th child item will be suppressed if its address equals with <i>addrBase + n * addrStep</i>.</p>
<p>Example:</p>
<pre class="cpp">

  <span class="keyword">if</span> d<span class="operator">.</span>isExpanded():
      with Children(d):
          with SubItem(d):
              d<span class="operator">.</span>putName(<span class="string">&quot;key&quot;</span>)
              d<span class="operator">.</span>putItem(key)
          with SubItem(d):
              d<span class="operator">.</span>putName(<span class="string">&quot;value&quot;</span>)
              d<span class="operator">.</span>putItem(value)

</pre>
<p>Note that this can be written more conveniently as:</p>
<pre class="cpp">

  d<span class="operator">.</span>putNumChild(<span class="number">2</span>)
  <span class="keyword">if</span> d<span class="operator">.</span>isExpanded():
      with Children(d):
          d<span class="operator">.</span>putSubItem(<span class="string">&quot;key&quot;</span><span class="operator">,</span> key)
          d<span class="operator">.</span>putSubItem(<span class="string">&quot;value&quot;</span><span class="operator">,</span> value)

</pre>
</div>
<!-- @@@creator-debugging-helpers.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="creator-debug-mode.html">Interacting with the Debugger</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-debugging-qml.html">Debugging Qt Quick Projects</a>
</p>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2019 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
